coap-message

CoAP mesage abstraction

This crate defines interfaces for readable and writable CoAP messages, which are used in the Internet of Things to transfer state in representations (REST). With these interfaces, it allows CoAP servers and clients to be written independently of the actual CoAP library that is used to serialize and deserialize the messages to the protocol.

The defined traits only cover the properties of CoAP at the request/response exchange level, not of the transport specific details. In particular, they do not expose tokens, message IDs or message types: Those are not even present in some transports, and in general there is no need for libraries to expose them. In the same vein, no methods are described to allocate messages: For constrained devices, that may not even be possible, and with CoAP libraries that support multiple configured transports, the type of message allocated may easily depend on the intended use. They do not cover remote addresses either, as these too are transport specific.

The crate also provides some trivial implementations of the types: [Code] for [u8], [OptionNumber] for [u16], as well as the [heapmessage::HeapMessage] for easy message manipulation and ownership on alloc systems.

Usage

A larger chunk of examples and demos is available at coap-message-demos, which illustrates both how to build coap-message based handlers, and how to use them in practice with different implementations of CoAP. Most of the applications in there use coap-message through the implementations in coap-handler, which provide short-cuts for common cases.

If you are on the implementing side of the message traits, you may want to have a look at coap-message-utils, which contains useful building blocks.

Error handling

The readable message types are designed with minimal fallability -- for example, iterating over the options can not raise a "premature end of message" style error, and the payload is always "present" (albeit possibly empty). This encodes the concept that having a message type implies validity of the message.

Libraries that insist on minimizing the cycles spent parsing (as typical in embedded situations) can opt to express the formatting error as a critical, not-safe-to-forward option (eg. the private-use number 65535). As consumers of a message that has not been checked in advance must check all options before acting on the message anyway, this ensures that the error does not go unnoticed.

For the writable message types, no errors are implemented either, necessarily resulting in panics when things go awry. The expectation is that applications communicate their allocation needs to the stack before populating the message, for example using the estimate-length function of coap-handler. As for codes and options not supported by a library, these types of errors are caught by the [Code] and [OptionNumber] fallible conversions.

License: MIT OR Apache-2.0